home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1998 June / SGI Freeware 1998 June.iso / dist / fw_ATxgopher.idb / usr / freeware / src / xgopher.1.3 / Documents / Popups.z / Popups
Text File  |  1998-01-21  |  10KB  |  256 lines
  1. Configuring placement of Xgopher popup windows
  2. ----------------------------------------------
  3.  
  4. Every Xgopher popup window has a default position that may be changed
  5. by the installer or user via the Xgopher resources.  This configurability
  6. will satisfy many needs: from the person who likes popups to appear at
  7. predictable places to the power user who always wants a popup to
  8. appear right at the mouse pointer to minimize movement.  A public-access
  9. kiosk running Xgopher as a single application can have all popups appear
  10. centered on the screen, a location which will have high-attention.
  11.  
  12. The positioning algorithm is straightforeward.  First, you identify
  13. a location on the display.  The options are 
  14.  
  15.     . at the mouse pointer
  16.     . relative to the Xgopher main window
  17.     . relative to the display screen
  18.  
  19. For the last two, the point may be an integer offset in pixels from the
  20. upper left corner of the window or display, or the offset may be 
  21. specified as a percentage of the width (height) of the window or display.
  22.  
  23. Second, you pick the horizontal and vertical justification of the 
  24. popup relative to that point.
  25.  
  26. Using this technique you can, for example, ask that the file copy
  27. popup (the one that requests a file name) be positioned with the
  28. center of its right edge coinciding with the center of the right edge
  29. of the main Xgopher panel.  The desired effect is something like this:
  30.     
  31.     +-----------------+
  32.     |  Xgopher window | 
  33.     |                 | 
  34.     |        +........+ 
  35.     |        |  copy  | 
  36.     |        | popup  | 
  37.     |        +........+ 
  38.     |                 | 
  39.     |                 | 
  40.     |                 | 
  41.     +-----------------+
  42.  
  43. The resources to do this are:
  44.  
  45.     Xgopher.copyPopup.positionFrom:        application
  46.     Xgopher.copyPopup.xPosition:        100
  47.     Xgopher.copyPopup.xPercent:        True
  48.     Xgopher.copyPopup.yPosition:        50
  49.     Xgopher.copyPopup.yPercent:        True
  50.     Xgopher.copyPopup.horizontalJustification:    Right
  51.     Xgopher.copyPopup.verticalJustification:    Center
  52.  
  53. Here is a summary of these 7 resources with the resource names, class
  54. names and the legal values.
  55.  
  56.     positionFrom        (class: PositionFrom)
  57.                 can take one of these values:
  58.         
  59.         . pointer        The popup will be justified against the
  60.                 current mouse pointer (cursor) location.
  61.                 (xPosition, xPercent, yPosition, and yPercent
  62.                 are unused).
  63.  
  64.         . application    The popup will be justified against a point
  65.                 within the Xgopher window.  If xPercent is
  66.                 True, the X position of the point is
  67.                 determined as a percent of the window width
  68.                 xPosition.  If xPercent is False, then
  69.                 xPosition is a number of pixels from the
  70.                 left edge of the window.  Y is computed the
  71.                 same way using yPercent and yPosition.
  72.  
  73.         . screen        Similar to "application", but using the
  74.                 display screen instead of the Xgopher window.
  75.  
  76.         . widget        Similar to "application", but using another
  77.                 window or widget as the reference window.
  78.                 This is of limited utility since you cannot
  79.                 specify the reference widget from the 
  80.                 resources file.  It is however, used for
  81.                 the default position of a text save
  82.                 popup - it is relative to that text window.
  83.  
  84.         . none        bypasses all positioning code, allowing only
  85.                 the window manager to have any placement
  86.                 control.
  87.     
  88.     xPosition        (class: Position)
  89.                 an integer interpreted as a number of
  90.                 pixels or as a percentage of some width
  91.                 (see positionFrom) depending on the
  92.                 value of xPercent.
  93.  
  94.     xPercent        (class: Percent)
  95.                 True or False - determines the way xPosition
  96.                 is interpreted.
  97.  
  98.     yPosition        (class: Position)
  99.                 Similar to xPosition, but for height.
  100.  
  101.     yPercent        (class: Percent)
  102.                 Similar to xPercent, but for height.
  103.  
  104.     horizontalJustification    (class: Justification)
  105.                 One of {left, center, or right}.  This is the
  106.                 horizontal alignment of the popup against the
  107.                 point determined by the other resources.
  108.  
  109.     verticalJustification    (class: Justification)
  110.                 One of {top, center, or bottom}.  This is the
  111.                 vertical alignment of the popup against the
  112.                 point determined by the other resources.
  113.  
  114.  
  115. The resource name for each popup is provided below along with its
  116. default position.  The class name for all popup positioning is "Popup".
  117. The set of resources that determines the default position is shown.
  118. Each can be modified to individual taste through the resource file.
  119.  
  120. The defaults are not chosen arbitrarily.  The idea is that panels
  121. which normally require more than one item of information before proceeding
  122. with Xgopher are popup up in a specific nearby location.
  123. The CSO name server panel can operate asynchronously with Xgopher
  124. is shown off to a side.  The index search, error, and information
  125. popups appear near the pointer for quick access.  The file save
  126. box is shown along with the associated text popup (since there may
  127. be more than one text display visible).
  128.  
  129. Of course, these are the choices of the author; you may change them
  130. to suit your taste.
  131.  
  132. To set the default value for any of these options for ALL popups,
  133. use the class name "Popup" instead of the specific instance name.
  134. For example, the following causes every popup to be shown centered
  135. on the screen:
  136.  
  137.     Xgopher.Popup.positionFrom:    screen
  138.     Xgopher.Popup.xPosition:    50
  139.     Xgopher.Popup.xPercent:        True
  140.     Xgopher.Popup.yPosition:    50
  141.     Xgopher.Popup.yPercent:        True
  142.     Xgopher.Popup.horizontalJustification:    Center
  143.     Xgopher.Popup.verticalJustification:    Center
  144.  
  145.  
  146. Notes:
  147.     1. After any popup position is calculated by Xgopher, it is adjusted
  148.        to keep the entire popup fully visible on the screen (the exception
  149.        2s noted in note 3 below).  Popups with positionFrom=none
  150.        will have no positioning done, so you are at the whim of the
  151.        window manager for window placement.
  152.     
  153.     2. In the positioning resources, the popup will still be moved
  154.        down and right by the amount of the window manager decorations.
  155.        Since Xgopher ultimately specifies only the upper left corner, and
  156.        simulates the center, right, and bottom justification, this 
  157.        affects center and right/bottom positions, but not top and left
  158.        alignment.  This is especially important to remember if you try
  159.        to position a popup at, for example the bottom edge of the screen.
  160.        In this case, part of the contents may be off the screen.  Xgopher
  161.        has no control of this.
  162.  
  163.     3. The "top level" shells (Xgopher main panel, text popups, and the
  164.        CSO name server popup panel) are usually placed by the window
  165.        manager at a level above the Xgopher application ( even if you
  166.        specify otherwise using these resources).  You may use the
  167.        window manager resources or individual geometry resource to
  168.        place these windows.  For example, to place the CSO name server
  169.        panel in the upper right of the screen, you can use:
  170.  
  171.            Xgopher.csoPopup.positionFrom:  none
  172.            Xgopher.csoShell.geometry:      -0+0
  173.  
  174.        The first disables any attempt by Xgopher to place this panel,
  175.        leaving it entirely to the window manager.  The second line
  176.        is a standard X geometry specification.
  177.  
  178.     4. There is a seeming naming inconsistency in the above note!  The
  179.        "xxxPopup" names is used exclusively for the popup positioning
  180.        resources.  The "xxxShell" names are used to emphasize that this
  181.        is the actual shell widget itself and any shell resources apply.
  182.  
  183.        In fact, there is not a 1-1 correspondence between the "xxxPopup"
  184.        and "xxxShell", but a many to one.  Some shells are used for more
  185.        than one purpose (the displayed-text file save and the file copy
  186.        for example).  The "xxxPopup" names are truly synthetic, not
  187.        necessarily corresponding to a single Xgopher entity.
  188.  
  189.  
  190. -------------------------------------------------------------------------
  191. Default popup positions
  192. -------------------------------------------------------------------------
  193.  
  194. The 7 values shown for each resource below are (in order):
  195.  
  196.     positionFrom, xPosition, yPosition, horizontalJustification,
  197.               verticalJustification, xPercent, yPercent
  198.  
  199. For each popup, the name is given, followed by the exact values
  200. used as a default position, followed by a concise description of
  201. what the values mean.
  202.         
  203.  
  204. versionPopup        APPLICATION, 50, 0, CENTER, TOP, True, True
  205.     (center, top) is at (50%, 0%) relative to the application window
  206.  
  207. singleItemPopup        APPLICATION, 0, 10, LEFT, TOP, True, True
  208.     (left, top) is at (0%, 10%)  relative to the application window
  209.  
  210. optionsPopup        APPLICATION, 0, 10, LEFT, TOP, True, True
  211.     (left, top) is at (0%, 10%)  relative to the application window
  212.  
  213. copyPopup        APPLICATION, 0, 10, LEFT, TOP, True, True
  214.     (left, top) is at (0%, 10%) relative to the application window
  215.  
  216. savePopup        WIDGET, 0, 10, LEFT, TOP, True, True
  217.     (left, top) is at (0%, 10%) relative to the associated text window
  218.             (Note that there is no way to specify any other window,
  219.             except the main application window from the resources file.)
  220.  
  221. cdPopup            WIDGET, 0, 33, LEFT, TOP, True, True
  222.     (left, top) is at (0%, 33%) relative to the save/copy window
  223.             (Note that there is no way to specify any other window,
  224.             except the save/copy window from the resources file.)
  225.  
  226. dupFilePopup        WIDGET, 50, 90, CENTER, TOP, True, True
  227.     (center, top) is at (50%, 90%) relative to the save/copy window
  228.             (Note that there is no way to specify any other window,
  229.             except the save/copy window from the resources file.)
  230.  
  231. csoPopup        APPLICATION, 66, 0, LEFT, TOP, True, True
  232.     (left, top) is at (66%, 0%)  relative to the application window
  233.  
  234. statusPopup        APPLICATION, 50, 50, CENTER, CENTER, True, True
  235.     (center, center) is at (50%, 50%) relative to the application window
  236.  
  237. indexPopup        APPLICATION, 50, 0, CENTER, TOP, True, True
  238.     (center, top) is at (50%, 0%) relative to the application window
  239.  
  240. infoPopup        POINTER, 0, 0, LEFT, BOTTOM, True, True
  241.     (left, bottom) is near the pointer
  242.  
  243. errorPopup        POINTER, 0, 0, LEFT, BOTTOM, True, True
  244.     (left, bottom) is near the pointer
  245.  
  246. fatalErrorPopup        SCREEN, 50, 50, CENTER, CENTER, True, True
  247.     Centered on the screen 
  248.  
  249. textPopup        NONE, 0, 0, LEFT, TOP, False, False
  250.     no default position.  (The geometry resource and/or the
  251.     window manager will place the text popup shell.)
  252.  
  253.     Note that ALL text popups will be subject to any specification
  254.     that you provide.  There is no way to specify different
  255.     positioning information for each text popup.
  256.